HAL I2S migration: List of applicable concepts

This section provides information about the HAL I2S applicable architecture concepts.

Concepts for I2S

Concept	Description
Separation of initialization and configuration functions	The initialization has been split into separate initialization and configuration functions: HAL_I2S_Init: initializes the handle and links it to an I2S instance. HAL_I2S_SetConfig: configures the I2S according to the user parameters.
Removal and conversion of init structure to configuration structure	The initialization structure has been removed and moved into hal_i2s_config_t configuration structure.
Renaming of the handle structure	The handle structure has been renamed to hal_i2s_handle_t.
Remove MspInit and MspDeInit callbacks	HAL_I2S_MspInit and HAL_I2S_MspDeInit are no longer available they are replaced by a user sequence to initializes and configures the I2S.
Introduction of HAL user data set/get APIs	Two functions to get and set user data are available HAL_I2S_SetUserData() and HAL_I2S_GetUserData().
Unitary configuration APIs	New APIs are available to get and set I2S features.
Individual callback registration APIs replace global register and unregister functions	The callback registration is handled by specific functions for each I2S event. These functions are used to register callback functions for different I2S events.
HAL implementation with LL inline functions	HAL I2S APIs now rely on LL APIs rather than performing direct register access.
Define statements and enumerations redirected to LL equivalents	HAL I2S define statements and enumerations are based on LL define statements.
Removal of hardware-related macros in HAL2	All hardware macros have been removed from the HAL I2S driver, and equivalent services are ensured through the LL APIs.
Revised and optimized HAL state machine	The I2S state machine has been reworked to ensure transitions of the peripheral functional states.
Revised and optimized HAL API status returns	The HAL I2S functions were updated to return: HAL_INVALID_PARAM: in case of a NULL p_config structure pointer. HAL_ERROR: in case of an error. HAL_TIMEOUT: in case of a user timeout. HAL_BUSY: in case of an ongoing process. HAL_OK: in case of a successfully completed operation.
Revised and optimized HAL error management	Involves redesigning the error handling mechanisms within the HAL to improve the detection, reporting, and handling of errors.
Replaced TypeDef suffix with _t in type names	All TypeDef parts of the HAL I2S driver have been removed and replaced by _t.
Replaced nonmodifiable pointers with const keywords	Const keywords have been added to non-modifiable pointers to ensure that either the pointer itself or the data it points to cannot be modified. This enhances code safety and readability, prevents unintended modifications, and renders code more robust and maintainable.
Assertion implementation and usage in HAL1	The parameters and state are checked using ASSERT_DBG_STATE and ASSERT_DBG_PARAM macros.
Merge HAL extension files with common ones and remove the EX prefix from APIs.	Only one HAL I2S header file remains and all macros, define statements, and functions from hal_i2s_ex.h have been moved to hal_i2s.h.
Provide RTOS-compatible acquire/release bus services for communication peripheral drivers.	New functions, HAL_I2S_AcquireBus() and HAL_I2S_ReleaseBus(), are provided to allow the acquisition and release of a HAL I2S handle, protecting a full sequence.
Add HAL PPP Services for Drivers with Handle to Retrieve Corresponding Peripheral Clock Frequency.	HAL I2S provides new API to retrieve clock frequency HAL_I2S_GetClockFreq.
Replace Finite Parameter Defines (Including PPP Instances) with Enum Types at HAL Levels.	Finite parameters (including I2S instances) have been converted into enumerated types (enums) at HAL level. This improves code readability, maintainability, and type safety.
Add HAL_PPP Prefix to All HAL Peripheral APIs (Defines, Macros, Types, and Functions).	All HAL I2S functions start with HAL_I2S. All HAL I2S enumerations and structures start with hal_i2s.

Other HAL I2S changes

Concept	Consideration
Add Pause and Resume features in IT mode	Introduce HAL_I2S_Pause_IT and HAL_I2S_Resume_IT functions, available only in Master mode.